
\section{\tikzname{} Interoperability}
\label{pgfplots:tikz:interoperability}

\PGFPlots{} uses \Tikz{}/\pgfname{} as its ``backend layer''. This implies that it
inherits most of \Tikz's graphical features and adds a lot of own stuff on top
of it. However, the coordinate systems of \Tikz{} and \PGFPlots{} do not match
up -- for good reason: \PGFPlots{} operates on logical (data) coordinates
whereas \Tikz{} operates on image coordinates.

Occasionally, one may want to synchronize both in order to generate a graphic.
In this context, ``synchronize both'' means that they really use the same
coordinate systems. This is far beyond the simple use case of ``enrich a
\PGFPlots{} picture by means of \Tikz{} annotations'', compare
Section~\ref{sec:pgfplots:annotations}.

Consequently, this section addresses the question how to match the coordinates
from \Tikz{} to \PGFPlots{} and vice versa. It explains how to match
coordinates and it discusses the necessary configuration.

There are a couple of keys in \PGFPlots{} which control the mapping of
coordinates. The purpose of these keys is to implement visualization
techniques, but they do things different than \Tikz{} (and they should). To
match coordinates with \Tikz{}, one needs the following aspects:
%
\begin{enumerate}
    \item Restrict your visualization type: a logarithmic axis simply may not
        fit into \Tikz{} (to be more precise: it may fit, but a \Tikz{} unit
        will correspond to a log unit in \PGFPlots).
    \item Configure matching unit vectors by means of the |x| and |y| keys.
        The default configuration of \Tikz{} is to use
        |x=1cm,y=1cm,z={(0,0)}|. Note that these settings are usually
        overridden by \PGFPlots{} in order to respect |width| and |height|
        (and |view| for three-dimensional axes).
    \item Disable the data scaling by means of |disabledatascaling|:
        \PGFPlots{} will internally apply linear coordinate transformations
        in order to provide the data range required for floating point
        arithmetics (using approximately floating point precision). Disabling
        the data scaling means to restrict yourself to the (small) data range
        supported by \Tikz{} -- but that's probably what you want in that
        case.
    \item Define |anchor| and position of the |axis|, probably using
        |anchor=origin,at={(0,0)}|. The |at={(0,0)}| configures \PGFPlots{}
        to place the axis at the \Tikz{} position |(0,0)| whereas
        |anchor=origin| means that \PGFPlots{} will place its data origin
        $(0,0,0)$ at the place designated by |at| (see
        Section~\ref{pgfplots:sec:align} for details).
    \item Make sure that the \PGFPlots{} axis contains the data origin
        $(0,0,0)$ in the displayed data range (i.e.\@ configure |xmin|,
        |xmax|, |ymin|, and |ymax| appropriately).

        Without this, the |anchor=origin| key required in the previous item
        will be truncated to the next coordinate which is part of the displayed
        range.
\end{enumerate}

\noindent Here is a simple example, first with \Tikz{}:
%
\begin{codeexample}[]
\begin{tikzpicture}
    \coordinate (Point) at (1,2);

    \draw [gray] (-1,-1) grid (3,3);
    \draw [blue,fill] (Point) circle (2pt)
        node [right] {(1,2)}
    ;
\end{tikzpicture}
\end{codeexample}
%
\noindent it displays a grid with $x,y\in[-1,3]$ and shows a node inside of it.
Now, we apply the keys discussed above to match this setting in \PGFPlots{}:
%
\begin{codeexample}[]
\begin{tikzpicture}
    \coordinate (Point) at (1,2);
\begin{axis}[
    % tell pgfplots to "grab" the axis at its
    % internal (0,0) coord:
    anchor=origin,
    % tell pgfplots to place its anchor at (0,0):
    % (This is actually the default and can
    % be omitted)
    at={(0pt,0pt)},
    % tell pgfplots to use the "natural" dimensions:
    disabledatascaling,
    % tell pgfplots to use the same unit vectors
    % as tikz:
    x=1cm,y=1cm,
    %
    % this is just as usual in pgfplots. I guess
    % it is only useful if (0,0) is part of the
    % range... try it out.
    xmin=-1,xmax=3, ymin=-1,ymax=3,grid=both,
]
    % this uses the point defined OUTSIDE of the axis
    \draw [blue,fill] (Point) circle (2pt)
        node [right] {(1,2)};

    % this uses a TIKZ coordinate (2,0) in the axis:
    \draw [blue,fill] (2,0) circle (2pt)
        node [right] {(2,0)};

    % this here will always work inside of an axis:
    \draw [blue,fill] (-1,0) circle (2pt)
        node [right] {(-1,0)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
%
\noindent The example demonstrates several things: first, it defines a
coordinate in the enclosing |tikzpicture| and uses it inside of the |axis| (at
the correct position). Second, it uses the standard \Tikz{} coordinate |(2,0)|
inside of the |axis|, and it is placed at the expected position. Third, it uses
the approach provided by \PGFPlots{} by using the |axis cs| to designate a
coordinate (this last approach does also work without the coordinate matching).

Here is an example which inserts a \PGFPlots{} graphics correctly into a
|tikzpicture|:
%
% \usepgfplotslibrary{patchplots}
\begin{codeexample}[]
% requires \usepgfplotslibrary{patchplots}
\begin{tikzpicture}
    \begin{axis}[
        % tell pgfplots to "grab" the axis at its internal (0,0) coord:
        anchor=origin,
        % tell pgfplots to place its anchor at (0,0):
        % (This is actually the default and can be omitted)
        at={(0pt,0pt)},
        % tell pgfplots to use the "natural" dimensions:
        disabledatascaling,
        % tell pgfplots to use the same unit vectors as tikz:
        x=1cm,y=1cm,
        %
        hide axis,
    ]
        \addplot [patch,patch type=coons,
            shader=interp,point meta=explicit]
        coordinates {
            (0,0)      [0] % first corner
            (1,-1)     [0] % bezier control point between (0) and (3)
            (4,0.7)    [0] % bezier control point between (0) and (3)
            %
            (3,2)      [1] % second corner
            (4,3.5)    [1] % bezier control point between (3) and (6)
            (7,2)      [1] % bezier control point between (3) and (6)
            %
            (7,1)      [2] % third corner
            (6,0.6)    [2] % bezier control point between (6) and (9)
            (4.5,-0.5) [2] % bezier control point between (6) and (9)
            %
            (5,-2)     [3] % fourth corner
            (4,-2.5)   [3] % bezier control point between (9) and (0)
            (-1,-2)    [3] % bezier control point between (9) and (0)
        };
    \end{axis}

    % this requires pgf 2.10
    \begin{scope}[every node/.style={circle,inner sep=2pt,fill=black}]
        \node [pin=140:first] at (0,0) {};
        \node [pin=second]    at (3,2) {};
        \node [pin=45:third]  at (7,1) {};
        \node [pin=0:fourth]  at (5,-2) {};
    \end{scope}
\end{tikzpicture}
\end{codeexample}
%
\noindent The example employs one of the |patch| plots of the |patchplots|
library. Since these graphical elements typically require depth information
(|z buffer|ing) and color data (|point meta|), they are only available inside
of \PGFPlots{}. However, the configuration above ensures that coordinates match
one-to-one between \PGFPlots{} and \Tikz{}. The |hide axis| flag disables
anything of \PGFPlots{}, so only the visualized |patch| plot
remains.\footnote{Note that the $(0,0,0)$ coordinate of \PGFPlots{} is part of
the data range here.}
